docs(infra): design Compass self-host runner + adoption strategy (RIG-3070) - #804

…sh macOS (RIG-3139)

Designs the reversal of the RIG-2542 client-only retirement: mode="embedded" returns to the Compass native app as the low-friction onboarding / local-dev front door, ADDED ALONGSIDE the fully-surviving client mode. The retirement's premise (the microVM Runner's KVM floor retiring local agent execution) is falsified now that podman is a permanent supported single-tenant tier per the trust-model boundary (DL-318, compass-obs #804). Covers the mode-selection contract, supervisor re-wire against the current stack, cross-OS preflight, bundle re-scope (sidecars return, postgres stays a DL-260 container), the macOS podman-machine provisioning spike, and the UI embedded boot arm.

Records the record on the ui/ design path (RIG-3113 dissolved product/ into ui/) and lands the ledger delta in DECISIONS.md: new rows DL-319 (dual-mode thesis), DL-320 (dual-mode app.toml), DL-321 (sidecar bundle sans postgres); status flips DL-235/237/238 → Superseded by DL-319/320/321. DL-236's standalone-compass-stack half stays Active.

Folds Matt's freeze-gate topology + backend feedback: the §Topology matrix separates the two independent axes (app mode: embedded/client; runner backend: podman/microVM) and records the recommended backend per funnel entry — embedded-local is podman-primary (macOS cannot do microVM; WSL2 has no KVM out of the box), self-host is microVM-recommended with podman the cost-sensitive tier, managed is microVM. Scrubs managed-hosted to the trust-model boundary only, with an OSS-core scope note keeping product-strategy specifics out of this repo. Adds three load-bearing open questions with recommendations for Matt's gate: OQ-9 (docker socket vs force-podman — force-podman: the --userns=keep-id:uid= isolation boundary is podman-specific), OQ-10 (apple/container as a macOS backend — defer: macOS-26 + Apple-silicon-only, pre-1.0), OQ-11 (embedded microVM on Linux — v1 container-only, follow-up). Also folds the prior review passes' podman-version FATAL preflight (delta 4, OQ-8) and the doc-comment reconciliations.

Refs RIG-3139
Spec-impact: adds the embedded-mode revival design record (Draft) under docs/designs/ui/
Ledger-impact: DL-319/320/321 added; DL-235/237/238 flipped to Superseded
Co-authored-by: Matt Wilkinson <matt@rigel.build>

…sh macOS (RIG-3139)

Designs the reversal of the RIG-2542 client-only retirement: mode="embedded" returns to the Compass native app as the low-friction onboarding / local-dev front door, ADDED ALONGSIDE the fully-surviving client mode. The retirement's premise (the microVM Runner's KVM floor retiring local agent execution) is falsified now that podman is a permanent supported single-tenant tier per the trust-model boundary (DL-318, compass-obs #804). Covers the mode-selection contract, supervisor re-wire against the current stack, cross-OS preflight, bundle re-scope (sidecars return, postgres stays a DL-260 container), the macOS podman-machine provisioning spike, and the UI embedded boot arm.

Records the record on the ui/ design path (RIG-3113 dissolved product/ into ui/) and lands the ledger delta in DECISIONS.md: new rows DL-319 (dual-mode thesis), DL-320 (dual-mode app.toml), DL-321 (sidecar bundle sans postgres); status flips DL-235/237/238 → Superseded by DL-319/320/321. DL-236's standalone-compass-stack half stays Active.

Folds Matt's freeze-gate topology + backend feedback: the §Topology matrix separates the two independent axes (app mode: embedded/client; runner backend: podman/microVM) and records the recommended backend per funnel entry — embedded-local is podman-primary (macOS cannot do microVM; WSL2 has no KVM out of the box), self-host is microVM-recommended with podman the cost-sensitive tier, managed is microVM. Scrubs managed-hosted to the trust-model boundary only, with an OSS-core scope note keeping product-strategy specifics out of this repo. Adds three load-bearing open questions with recommendations for Matt's gate: OQ-9 (docker socket vs force-podman — force-podman: the --userns=keep-id:uid= isolation boundary is podman-specific), OQ-10 (apple/container as a macOS backend — defer: macOS-26 + Apple-silicon-only, pre-1.0), OQ-11 (embedded microVM on Linux — v1 container-only, follow-up). Also folds the prior review passes' podman-version FATAL preflight (delta 4, OQ-8) and the doc-comment reconciliations.

Refs RIG-3139
Spec-impact: adds the embedded-mode revival design record (Draft) under docs/designs/ui/
Ledger-impact: DL-319/320/321 added; DL-235/237/238 flipped to Superseded
Co-authored-by: Matt Wilkinson <matt@rigel.build>

…sh macOS (RIG-3139) (#833)

Designs the reversal of the RIG-2542 client-only retirement: mode="embedded" returns to the Compass native app as the low-friction onboarding / local-dev front door, ADDED ALONGSIDE the fully-surviving client mode. The retirement's premise (the microVM Runner's KVM floor retiring local agent execution) is falsified now that podman is a permanent supported single-tenant tier per the trust-model boundary (DL-318, compass-obs #804). Covers the mode-selection contract, supervisor re-wire against the current stack, cross-OS preflight, bundle re-scope (sidecars return, postgres stays a DL-260 container), the macOS podman-machine provisioning spike, and the UI embedded boot arm.

Records the record on the ui/ design path (RIG-3113 dissolved product/ into ui/) and lands the ledger delta in DECISIONS.md: new rows DL-319 (dual-mode thesis), DL-320 (dual-mode app.toml), DL-321 (sidecar bundle sans postgres); status flips DL-235/237/238 → Superseded by DL-319/320/321. DL-236's standalone-compass-stack half stays Active.

Folds Matt's freeze-gate topology + backend feedback: the §Topology matrix separates the two independent axes (app mode: embedded/client; runner backend: podman/microVM) and records the recommended backend per funnel entry — embedded-local is podman-primary (macOS cannot do microVM; WSL2 has no KVM out of the box), self-host is microVM-recommended with podman the cost-sensitive tier, managed is microVM. Scrubs managed-hosted to the trust-model boundary only, with an OSS-core scope note keeping product-strategy specifics out of this repo. Adds three load-bearing open questions with recommendations for Matt's gate: OQ-9 (docker socket vs force-podman — force-podman: the --userns=keep-id:uid= isolation boundary is podman-specific), OQ-10 (apple/container as a macOS backend — defer: macOS-26 + Apple-silicon-only, pre-1.0), OQ-11 (embedded microVM on Linux — v1 container-only, follow-up). Also folds the prior review passes' podman-version FATAL preflight (delta 4, OQ-8) and the doc-comment reconciliations.

Refs RIG-3139
Spec-impact: adds the embedded-mode revival design record (Draft) under docs/designs/ui/
Ledger-impact: DL-319/320/321 added; DL-235/237/238 flipped to Superseded

Co-authored-by: Matt Wilkinson <matt@rigel.build>

…-3238)

ReviewDesign869 returned 1 high / 2 medium / 4 low on PR #869. Grounding
fidelity was clean (all code + cross-record citations verify at source);
these are ledger-collision and plan-completeness fixes. All folded; the two
mediums each also surface a load-bearing fork to Matt as a new OQ rather than
being decided here.

- HIGH (ledger collision): DL-326's Decision cell cited DL-325, an unlanded
  number double-claimed by #804 (RIG-3070) and #868 (RIG-2863). Since #868 is
  review-ready it may take DL-325 for an unrelated decision, and the cell is
  immutable after append. Re-cite the runner trust-model split by name+issue
  (RIG-3070 / PR #804), not the contested number, and add a Global Constraint
  ID-allocation + freeze-order note (mirroring the sibling embedded-revival
  record's GC6): re-grep main's ledger tail before landing, and the record
  does not depend on #804 landing first.
- MEDIUM (T-4 premise gap): removing podman-machine removes the Linux VM the
  runner runs IN on macOS today (compass-local-dev:194-205 ruled the runner
  runs INSIDE the VM), so apple-container forces the runner to run natively on
  darwin. Add a T-1(f) spike leg, an Approach reason-2 caveat, a T-4 scope
  note, and OQ-12 (load-bearing Matt fork: does a NO re-open adoption?).
- MEDIUM (T-2 podman surface): the stack has a second hard-coded podman shell
  (postgres_container.go:246-259 + collector_container.go:62) and ImageEnsurer
  is podman-hardwired at its production constructor (image.go:44-45). DL-260
  keeps postgres a rootless-podman container, so a macOS host still needs
  podman for the stack. Widen T-2's off-interface enumeration, concede the
  scoped "no machine" win in Approach reason 2, and add OQ-13 (Matt fork:
  postgres to apple-container, or --database-external as the macOS default?).
- LOW x4: nine-verbs wording (Resize is the ninth, not a tenth); image.go
  ImageExists citation span (:713, outside the cited :681-684); the
  OQ-1..OQ-4 gate carve-out for OQ-5's judgment call; DL-326 record link
  gains the §Approach anchor for the one-hop convention.

Checks: markdownlint 0 errors; design-ledger-gate OK (291 rows, 122 headers).
Status stays Draft — freezes Active on merge.

Refs RIG-3238
Co-authored-by: Matt Wilkinson <matt@rigel.build>

…-3238)

ReviewDesign869 returned 1 high / 2 medium / 4 low on PR #869. Grounding
fidelity was clean (all code + cross-record citations verify at source);
these are ledger-collision and plan-completeness fixes. All folded; the two
mediums each also surface a load-bearing fork to Matt as a new OQ rather than
being decided here.

- HIGH (ledger collision): DL-326's Decision cell cited DL-325, an unlanded
  number double-claimed by #804 (RIG-3070) and #868 (RIG-2863). Since #868 is
  review-ready it may take DL-325 for an unrelated decision, and the cell is
  immutable after append. Re-cite the runner trust-model split by name+issue
  (RIG-3070 / PR #804), not the contested number, and add a Global Constraint
  ID-allocation + freeze-order note (mirroring the sibling embedded-revival
  record's GC6): re-grep main's ledger tail before landing, and the record
  does not depend on #804 landing first.
- MEDIUM (T-4 premise gap): removing podman-machine removes the Linux VM the
  runner runs IN on macOS today (compass-local-dev:194-205 ruled the runner
  runs INSIDE the VM), so apple-container forces the runner to run natively on
  darwin. Add a T-1(f) spike leg, an Approach reason-2 caveat, a T-4 scope
  note, and OQ-12 (load-bearing Matt fork: does a NO re-open adoption?).
- MEDIUM (T-2 podman surface): the stack has a second hard-coded podman shell
  (postgres_container.go:246-259 + collector_container.go:62) and ImageEnsurer
  is podman-hardwired at its production constructor (image.go:44-45). DL-260
  keeps postgres a rootless-podman container, so a macOS host still needs
  podman for the stack. Widen T-2's off-interface enumeration, concede the
  scoped "no machine" win in Approach reason 2, and add OQ-13 (Matt fork:
  postgres to apple-container, or --database-external as the macOS default?).
- LOW x4: nine-verbs wording (Resize is the ninth, not a tenth); image.go
  ImageExists citation span (:713, outside the cited :681-684); the
  OQ-1..OQ-4 gate carve-out for OQ-5's judgment call; DL-326 record link
  gains the §Approach anchor for the one-hop convention.

Checks: markdownlint 0 errors; design-ledger-gate OK (291 rows, 122 headers).
Status stays Draft — freezes Active on merge.

Refs RIG-3238
Co-authored-by: Matt Wilkinson <matt@rigel.build>

…sign (RIG-3238)

ReviewDesign869r2 verified all 7 round-1 findings CLOSED but caught two
mediums the round-1 fold's own new prose introduced. Both are mechanical
text corrections with no design consequence.

- MEDIUM (guard-bullet facts): the ID-allocation/freeze-order Global
  Constraint bullet had wrong PR->DL attributions on every clause. Ground
  truth (verified via gh pr diff + main's ledger): main's tail ends at DL-324
  (landed by #870, merged); DL-325 is claimed by #804 (RIG-3070, draft) AND
  #859 (RIG-2863); DL-326 -- this record's own number -- is claimed by #859,
  which is review-ready (NOT draft). The bullet missed the real live collision
  (#859 on DL-326) and named #868 (which actually claims DL-327). Rewrote the
  factual clauses to match; kept the two correct load-bearing clauses (the
  MUST-re-grep-before-landing instruction and does-NOT-depend-on-#804). The
  immutable DL-326 cell was already merge-order-safe (name+issue cite), so
  this only corrected mutable prose.
- MEDIUM (unknown-count consistency): round-1 widened the ledger cell from
  five to six unknowns (adding runner-on-darwin / OQ-12) but left three "five"
  sites in the record body: the Why-STAGED enumeration, the reject-default
  alternative, and the T-1 task heading. Aligned all three to six + OQ-12, and
  aligned the threat classification (OQ-1, OQ-2, and OQ-12 threaten adoption)
  with the cell's widened re-open trigger.
- LOW: re-wrapped two range-overwrite orphan lines to the file's ~72-col width.

Checks: markdownlint 0 errors; design-ledger-gate OK (291 rows, 122 headers).
Status stays Draft -- freezes Active on merge.

Refs RIG-3238
Co-authored-by: Matt Wilkinson <matt@rigel.build>